كيفية كتابة كود نظيف سهل القراءة والصيانة

 

الكود يُقرأ أكثر بكثير مما يُكتب: تقرؤه أنت بعد شهور، ويقرؤه زميل جديد، ويقرؤه المراجع قبل الدمج. والكود النظيف ليس كودًا جميلًا فحسب، بل كود يفهمه غيرك بسرعة ويعدله دون خوف. نعرض هنا ممارسات عملية تنفع في أي لغة.

كيف تختار أسماء تشرح نفسها؟

الأسماء أهم أدوات الوضوح، وكثير من الكود الغامض سببه أسماء مبهمة:

• اسم يصف الغرض لا النوع: unpaidInvoices أوضح من list2 أو data، فالقارئ يفهم المحتوى دون البحث عن مصدره.

• أفعال للدوال وأسماء للمتغيرات: calculateTotal() تقول ماذا تفعل، وtotal تقول ماذا تحمل. والقيم المنطقية تبدأ غالبًا بـ is أو has مثل isActive.

• تجنب الاختصارات الغامضة: usr وtmp وx تختصر ثوانٍ في الكتابة وتكلف دقائق في الفهم. استثناء مقبول للمتغيرات القصيرة الأمد كمؤشر حلقة صغيرة.

• اتساق التسمية: إن اخترت fetch للجلب فلا تستعمل get وretrieve لنفس المعنى في موضع آخر. واتبع عرف لغتك في الصيغة، كـ camelCase أو snake_case.

• لا تضمّن النوع في الاسم بلا حاجة: مع أنواع اللغة الحديثة صار userList أقل فائدة من users.

• الثوابت بدل الأرقام السحرية: MAX_LOGIN_ATTEMPTS = 5 أوضح من رقم 5 مبعثر في الكود، وتعدله في مكان واحد.

• اللغة: اكتب الأسماء بالإنجليزية في أغلب المشاريع لانتشار الأدوات والفرق، واتفقوا كفريق على عرف واحد، والتعليقات يمكن أن تكون بلغة فريقك.

كيف تكتب دوالًا صغيرة ذات مسؤولية واحدة؟

الدالة الجيدة تفعل شيئًا واحدًا وتفعله بوضوح، وهذا يسهل قراءتها واختبارها:

• مسؤولية واحدة: إن احتجت إلى كلمة «و» لوصف الدالة (تتحقق من البيانات وتحفظها وترسل بريدًا) ففكر في تقسيمها.

• قصر مناسب: لا قاعدة صارمة بعدد الأسطر، لكن الدالة التي تحتاج إلى تمرير طويل لفهمها تستحق التقسيم.

• عدد معاملات قليل: كلما زادت المعاملات صعب الاستعمال والاختبار. وإن تجمعت ثلاثة أو أربعة، ففكر في تجميعها في كائن.

• تجنب الآثار الجانبية الخفية: دالة اسمها getUser لا يجب أن تغير شيئًا في القاعدة. والمفاجآت تصنع أخطاء يصعب اصطيادها.

• الرجوع المبكر: تحقق من الحالات الخاصة في البداية وأرجع، بدل تداخل شروط عميقة تشكل «هرمًا» من الأقواس.

• مستوى تجريد واحد: لا تخلط تفاصيل منخفضة المستوى كمعالجة نص مع منطق عمل عالي المستوى في الدالة نفسها.

• قابلية الاختبار: دالة تأخذ مدخلات وتعيد مخرجات بلا اعتماد على حالة عامة أسهل في الاختبار.

متى تفيد التعليقات ومتى تضر؟

التعليق الجيد يشرح «لماذا» لا «ماذا»، والتعليق الزائد يتقادم ويكذب:

• علّق على القرار لا على الظاهر: // نستخدم المهلة 30 ثانية لأن الخدمة الخارجية بطيئة أحيانًا مفيد، أما // يزيد العداد فلا.

• حاول إزالة الحاجة للتعليق: إن احتاج سطر إلى شرح، فقد يكفيه اسم أوضح أو دالة مستخرجة.

• حدّث التعليقات مع الكود: تعليق قديم يناقض الكود أسوأ من غيابه.

• وثّق الواجهات العامة: وصف ما تفعله الدالة وقيود مدخلاتها وأخطائها المحتملة، بصيغة توثيق اللغة.

• لا تترك كودًا معطلًا في التعليقات: Git يحفظ التاريخ، فاحذف ما لا تحتاج.

• علامات المهام: TODO مع سبب أو رقم مشكلة ترتبط بتتبع حقيقي، لا ملاحظات مهجورة.

• اشرح المنطق المعقد أو المقصود: كمعادلة أو التفاف على خلل في مكتبة، مع رابط للمرجع.

كيف تنظم الملفات والبنية؟

حين يكبر المشروع، تصبح البنية هي ما يحافظ على الوضوح:

• اجمع ما يتغير معًا: نظّم بحسب الميزة (الطلبات، المستخدمون) أو بحسب الطبقة (واجهات، خدمات، بيانات)، واختر ما يناسب فريقك واتبعه باتساق.

• ملفات ذات غرض واضح: ملف ضخم يضم كل شيء يصعب تصفحه ويكثر فيه التعارض بين المطورين.

• تجنب التبعيات الدائرية: حين تعتمد وحدة على أخرى وتعتمد الأخرى عليها، تتعقد الاختبارات والتغيير.

• افصل الإعدادات عن الكود: وافصل الأسرار عن المستودع.

• أسماء ملفات مفهومة: وهيكل مجلدات يمكن لوافد جديد استنتاجه.

• ملف README: يشرح المشروع وطريقة تشغيله واختباره، وهو أول ما يقرأه كل من يصل إليه.

• لا تفرط في الهندسة: لا حاجة إلى طبقات وأنماط لمشروع صغير. أضف البنية عندما يظهر الألم، لا قبله.

كيف تتجنب التكرار والتعقيد؟

بعض الأنماط تتكرر في الكود المتعب. وتجنبها يخفف الصيانة:

• لا تكرر نفسك (DRY) بحكمة: إن تكرر المنطق نفسه في ثلاثة أماكن فاستخرجه في دالة. لكن لا تدمج أشياء متشابهة ظاهريًا ومختلفة في الغرض، فالتجريد الخاطئ أسوأ من التكرار.

• أبسط حل يعمل: كثير من التعقيد ينشأ من تصميم لاحتياجات متخيلة. احل مشكلة اليوم بوضوح، وعدل حين تتغير.

• تقليل الحالة المتغيرة: كلما قلّت المتغيرات التي تتبدل عبر الكود سهل فهمه. ففضّل القيم التي لا تتغير حيث أمكن.

• معالجة الأخطاء بوضوح: لا تبتلع الاستثناءات بصمت، ولا تعالجها بعيدًا عن مكان فهمها. وأعطِ رسائل تفيد من يقرأ السجلات.

• تجنب التداخل العميق: أكثر من ثلاثة مستويات من الشروط والحلقات علامة على ضرورة التبسيط.

• اكتب كودًا متوقعًا: يفعل ما يوحي به اسمه ويتبع عرف لغته، فلا يفاجئ القارئ.

• احذف الكود الميت: المتغيرات والدوال غير المستعملة تربك القارئ وتوهمه بوجود وظيفة.

كيف تحافظ على الجودة بالأدوات والمراجعة؟

النظافة لا تعتمد على الانضباط الفردي فقط، بل على نظام يدعمه:

• منسق الكود (Formatter): أداة مثل Prettier أو Black تنسق تلقائيًا، فتنتهي النقاشات عن المسافات وتتناسق الملفات.

• المحلل الساكن (Linter): مثل ESLint أو Ruff أو غيرهما، يكشف أنماطًا مشبوهة ومتغيرات غير مستعملة قبل التشغيل.

• الاختبارات الآلية: شبكة أمان تتيح لك إعادة الهيكلة دون خوف، وهي موضوع المقال التالي.

• مراجعة الكود: عينان إضافيتان تكتشفان ما لا تراه، وتنشران المعرفة. راجع بأدب وركز على الوضوح والمنطق لا الذوق الشخصي.

• إعادة الهيكلة المستمرة: حسّن الكود الذي تلمسه قليلًا في كل مرة (قاعدة الكشاف: اترك المكان أنظف مما وجدته)، بدل مشروع تنظيف ضخم يؤجل.

• التكامل المستمر: يشغل المنسق والمحلل والاختبارات عند كل دفعة تلقائيًا.

• أدلة الأسلوب: استعن بأدلة أسلوب منشورة للغتك، واتفق مع فريقك على استثناءاتها.

• قياس الدين التقني: سجل المشكلات المعروفة لتعالجها عن قصد لا بالصدفة.

أسئلة شائعة عن الكود النظيف

هل الكود النظيف أبطأ في الأداء؟

في الأغلب لا فرق يذكر. الوضوح لا يعني البطء. وإن ثبت بالقياس أن جزءًا بطيء فحسّنه مع توثيق السبب.

كيف أتعلم كتابة كود نظيف؟

اقرأ كود مشاريع جيدة، وراجع كودك بعد أسبوع من كتابته، واطلب مراجعة من أكثر خبرة. وكتاب «Clean Code» وغيره مراجع معروفة، مع الانتباه إلى أن بعض نصائحها محل نقاش.

هل أنفذ القواعد كلها بصرامة؟

القواعد إرشادات لا قوانين. السؤال المقياس: هل يفهم زميلي هذا بسرعة ويعدله بأمان؟ اتبع القاعدة حين تخدم ذلك.